AWS CLI のコンフィグファイルと環境変数とコマンドラインオプションで指定できる内容をまとめて確認してみた
コンバンハ、千葉（幸）です。
~/.aws/config、いじってますか？
[default] region = ap-northeast-1 output = json [profile chiba] region = ap-northeast-1 output = json role_arn = arn:aws:iam::999999999999:role/chibayuki-role source_profile = jump-account mfa_serial = arn:aws:iam::000000000000:mfa/cm-chiba.yukihiro
~/.aws/configでデフォルトリージョンや出力形式、スイッチロールのための設定などを行う機会は多いかと思います。ここで設定可能な項目は他にもたくさんあり、その数は30個以上にのぼります。
今回はその一覧をまとめてみました。以下一覧をベースとしています。
設定項目に対応する環境変数やコマンドライオプションがある（場合がある）ので、それも一緒にまとめています。
AWS CLI コンフィグファイルの基本をおさらい
一覧の確認の前に、基本的な考え方を押さえておきましょう。
~/.aws/config と ~/.aws/credentials
以下のように aws configure を実行したとします。（アクセスキーの値はドキュメントに載っているサンプルのものです。）
$ aws configure AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY Default region name [None]: us-west-2 Default output format [None]: json
このコマンドを実行すると以下のように二つのファイルに設定が行われます。
[default] aws_access_key_id=AKIAIOSFODNN7EXAMPLE aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
[default] region=us-west-2 output=json
認証情報（アクセスキーとシークレットアクセスキー）のみ別ファイルに保存され、それ以外の設定は~/.aws/configに保存されます。
こういった（両ファイルにまたがった）設定内容の集まりをプロファイルと呼びます。ここではdefaultプロファイルを使用しているということになります。
名前付きプロファイル
プロファイルを複数持つこともできます。先程の aws configure に--profileオプションを指定し、プロファイル名にSampleを指定したとします。
$ aws configure --profile Sample AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY Default region name [None]: us-west-2 Default output format [None]: json
各設定ファイルにはSampleという名称でプロファイルが追加されます。
[default] aws_access_key_id=AKIAIOSFODNN7EXAMPLE aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY [Sample] aws_access_key_id=AKIAIOSFODNN7EXAMPLE aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
[default] region=us-west-2 output=json [Sample] region=us-west-2 output=json
（ここではdefaultとSampleに同じ値を入れましたが、一般的には別の設定値を入れます。）
このように複数プロファイルを持てます。aws configure を使用せずに設定ファイルを直接編集しても設定できます。
コンフィグ設定と優先順位
~/.aws/configの設定内容は環境変数やコマンドラインオプションによって上書きされます。
プロファイルでデフォルトリージョンとしてus-west-2が指定されていたとします。
[default] region=us-west-2 output=json
この状態で特に指定なしに AWS CLI を実行するとコマンド実行対象のリージョンはus-wast-2となります。
ここで環境変数AWS_DEFAULT_REGIONを設定すれば、設定は上書きされます。（環境変数が有効な間のみ）
$ export AWS_DEFAULT_REGION=ap-northeast-1
さらにその状態でコマンドラインオプション--regionを使用すれば、その指定が優先されます。（オプションを付与したコマンド一回のみ）
$ aws ec2 describe-vpcs\ --region ap-northeast-3
今回取り上げた項目では以下順に優先されます。
- コマンドラインオプション
- 環境変数
- AWS CLI コンフィグファイル
とは言え、すべての設定項目においてそれに対応するコマンドラインオプションや環境変数が存在するわけではないことに注意してください。
また、その他にもいくつか優先順位が考慮される要素があります。詳細は以下を参照してください。
AWS CLI コンフィググローバル設定の一覧
~/.aws/configで設定できる項目の一覧をまとめました。
AWS CLI のバージョンによって使用できるか否かが異なるため、「v1,v2」の列で表現しています。また、設定項目を上書きできる環境変数やコマンドラインオプションがあるものはそれを記載しています。
| # | 設定項目名 | 概要 | デフォルト値 | v1 | v2 | 環境変数 | コマンドラインオプション |
|---|---|---|---|---|---|---|---|
| 1 | api_versions | 旧 API バージョンを指定する際に使用 | なし（最新Ver） | ● | - | なし | なし |
| 2 | aws_access_key_id | AWS アクセスキーの指定 | なし | ● | ● | AWS_ACCESS_KEY_ID |
なし |
| 3 | aws_secret_access_key | AWS シークレットアクセスキーの指定 | なし | ● | ● | AWS_SECRET_ACCESS_KEY |
なし |
| 4 | aws_session_token | AWS セッショントークンの指定 | なし | ● | ● | AWS_SESSION_TOKEN |
なし |
| 5 | ca_bundle | SSL 証明書を検証するために使用される CA 証明書バンドルを指定 | なし（ツール標準） | ● | ● | AWS_CA_BUNDLE |
--ca-bundle |
| 6 | cli_auto_prompt | 自動プロンプト（各種補完）の指定 | off | - | ● | AWS_CLI_AUTO_PROMPT |
--cli-auto-prompt、--no-cli-auto-prompt |
| 7 | cli_binary_format | バイナリインプットパラメータをどう解釈するかを指定 | base64 | - | ● | なし | なし |
| 8 | cli_follow_urlparam | URL リンク先のコンテンツをパラメータ値として使用するかどうかを指定 | true | ● | - | なし | なし |
| 9 | cli_pager | 出力に使用されるページャープログラムを指定 | なし（OS準拠） | - | ● | AWS_PAGER |
--no-cli-pager |
| 10 | cli_timestamp_format | 出力に含まれるタイムスタンプの形式を指定 | iso8601(v2),wire(v1) | ● | ● | なし | なし |
| 11 | credential_process | 認証情報を生成・取得するための外部コマンドを指定 | なし | ● | ● | なし | なし |
| 12 | credential_source | IAM ロールを引き受けるために使用する認証情報を検索する場所を指定 | なし | ● | ● | なし | なし |
| 13 | duration_seconds | ロールセッションの最大期間を秒単位で指定 | 3600 | ● | ● | なし | なし |
| 14 | external_id | サードパーティーがロールを引き受けるために使用される独自の識別子を指定 | なし | ● | ● | なし | なし |
| 15 | max_attempts | AWS CLI 再試行ハンドラが使用する最大再試行回数を指定 | retry_mode 準拠 | ● | ● | AWS_MAX_ATTEMPTS |
なし |
| 16 | mfa_serial | ロールを引き受けるときに使用する MFA デバイスの ID を指定 | なし | ● | ● | なし | なし |
| 17 | output | コマンドのデフォルトの出力形式を指定 | json | ● | ● | AWS_DEFAULT_OUTPUT |
--output |
| 18 | parameter_validation | クライアント側でパラメータの検証をするかどうかを指定 | true | ● | ● | なし | なし |
| 19 | region | コマンドのリクエスト送信先の AWS リージョンを指定 | なし | ● | ● | AWS_DEFAULT_REGION |
--region |
| 20 | retry_mode | AWS CLI が使用する再試行モードを指定 | standard(v2),legacy(v1) | ● | ● | AWS_RETRY_MODE |
なし |
| 21 | role_arn | コマンドの実行に使用する IAM ロールの ARN を指定 | なし | ● | ● | AWS_ROLE_ARN |
なし |
| 22 | role_session_name | ロールを引き受けたセッションに適用する名前を指定 | なし | ● | ● | AWS_ROLE_SESSION_NAME |
なし |
| 23 | source_profile | IAM ロールを引き受けるために使用する名前付きプロファイルを指定 | なし | ● | ● | なし | なし |
| 24 | sso_account_id | AWS SSO ユーザー用の IAM ロールがある AWS アカウント ID を指定 | なし | - | ● | なし | なし |
| 25 | sso_region | AWS SSO ポータルホストを含む AWS リージョンを指定 | なし | - | ● | なし | なし |
| 26 | sso_role_name | AWS SSO 用の IAM ロール名を指定 | なし | - | ● | なし | なし |
| 27 | sso_start_url | AWS SSO ユーザーポータルを指す URL を指定 | なし | - | ● | なし | なし |
| 28 | sts_regional_endpoints | AWS STS との通信に使用するサービスエンドポイントを指定 | regional(v2),legacy(v1) | ● | ● | AWS_STS_REGIONAL_ENDPOINTS |
なし |
| 29 | web_identity_token_file | Web ID トークンファイルのパスを指定 | なし | ● | ● | AWS_WEB_IDENTITY_TOKEN_FILE |
なし |
| 30 | tcp_keepalive | クライアントが TCP キープアライブバケットを使用するかどうかを指定 | true | ● | ● | なし | なし |
AWS CLI コンフィグ S3 カスタムコマンド設定
ここまで見てきたのは AWS CLI コンフィグのグローバル設定であり AWS サービスを問わず適用されます。S3 に限定して適用が可能な設定項目があるため、それを取り上げます。
設定項目は以下のようにs3の中でネストして使用します。
[profile development] s3 = max_concurrent_requests = 20 max_queue_size = 10000 multipart_threshold = 64MB multipart_chunksize = 16MB max_bandwidth = 50MB/s use_accelerate_endpoint = true addressing_style = path
すべての項目はv1とv2の両方で使用できます。
| # | 設定項目名 | 概要 | デフォルト | v1 | v2 |
|---|---|---|---|---|---|
| 1 | addressing_style | パス形式か仮想ホスト形式かを指定 | auto | ● | ● |
| 2 | payload_signing_enabled | sigv4ペイロードをSHA256署名するかどうかを指定 | false | ● | ● |
| 3 | use_dualstack_endpoint | S3 デュアル IPv4 / IPv6エンドポイントを使用するかを指定 | false | ● | ● |
| 4 | use_accelerate_endpoint | アクセラレートエンドポイントを使用するかを指定 | false | ● | ● |
| 5 | max_bandwidth | S3との通信の最大帯域幅を指定 | 制限なし | ● | ● |
| 6 | max_concurrent_requests | 同時リクエストの最大数を指定 | 10 | ● | ● |
| 7 | max_queue_size | タスクキュー内のタスクの最大数を指定 | 1000 | ● | ● |
| 8 | multipart_chunksize | マルチパート転送に使用するチャンクサイズを指定 | 8MB | ● | ● |
| 9 | multipart_threshold | マルチパート転送を行うサイズのしきい値を指定 | 8MB | ● | ● |
AWS CLI の環境変数
ここまで確認してきたコンフィグの設定項目に対応するものがない環境変数もあるため、ここで取り上げます。
| 環境変数名 | 概要 | デフォルト | v1 | v2 | コマンドラインオプション |
|---|---|---|---|---|---|
| AWS_CLI_FILE_ENCODING | テキストファイルに使用されるエンコーディングを指定 | ロケールに一致 | - | ● | なし |
| AWS_CONFIG_FILE | コンフィグファイルのパスを指定 | ~/.aws/config | ● | ● | なし |
| AWS_EC2_METADATA_DISABLED | IMDSの使用を無効化するかどうかを指定 | false | ● | ● | なし |
| AWS_PROFILE | AWS CLI プロファイルを指定 | default | ● | ● | --profile |
| AWS_SHARED_CREDENTIALS_FILE | クレデンシャルファイルのパスを指定 | ~/.aws/credentials | ● | ● | なし |
AWS CLI コマンドラインオプション
同じように、コンフィグ設定項目にも環境変数にも対応するものがないコマンドラインオプションがあるため、ここで取り上げます。
| # | オプション名 | 概要 | デフォルト | v1 | v2 |
|---|---|---|---|---|---|
| 1 | --cli-connect-timeout | ソケット接続のタイムアウトを秒数で指定 | なし | ● | ● |
| 2 | --cli-read-timeout | ソケット読み取りのタイムアウトを秒数で指定 | なし | ● | ● |
| 3 | --color | カラー出力のサポートを指定 | auto | ● | ● |
| 4 | --debug | デバッグログの出力を指定 | なし | ● | ● |
| 5 | --endpoint-url | エンドポイントの URL を指定 | なし | ● | ● |
| 6 | --no-paginate | ページ遷移を無効化を指定 | なし | ● | ● |
| 7 | --no-sign-request | クレデンシャルファイルの読み込みを指定 | なし | ● | ● |
| 8 | --query | JMESPath query によるフィルタリングを指定 | なし | ● | ● |
| 10 | --version | AWS CLI のバージョンを表示 | なし | ● | ● |
終わりに
AWS CLI のコンフィグファイル、環境変数、コマンドラインオプションで指定できる内容をまとめてみました。
改めて見てみると設定項目の数がかなり多く、細かい部分まで設定変更ができることが分かりました。全部を使いこなす必要はありませんが、「こういう設定もできたな」ということを覚えておくと役に立つ時が来るかもしれません。
特に、 S3 まわりで転送のパフォーマンスが出ていない……という時のチューニングに思い出したりすると幸せになりそうです。
ご参考ください。
以上、 チバユキ (@batchicchi) がお送りしました。
